vect: A Vividus Source Code Library for Vector Math.
Users must read the license agreement before using this library. The licensing agreement is found in the file "Vividus Licensing."
Vividus Source Code Library Documentation:
Vividus Source Code Libraries are documented in two locations. First, every library folder includes a documentation file. This documentation file discusses general issues related to the library such as common data formats, efficiency considerations, types of routines available, conventions, assumptions, and etc. The second type of documentation is individual subroutine documentation. This is included in the subroutine itself. Vividus recommends obtaining a source code browser to quickly index to subroutine documentation. One example is PopUpFuncs by Eric Slosser [SciComp Software; 2912 Claremont Ave #21; Berkeley CA 94705].
There may appear to be other forms of documentation in the library folder and in the source code itself. This documentation is mainly for internal Vividus use and developer curiosity.
Revision information and histories are included at the end of this document.
Introduction and Requirements:
Vect is a vector abstraction library. It provides data types and operations for vector math.
The vect library has been developed with THINKC version 5.0 and should be compilable with other C compilers with little or no modification.
Installation (for THINKC):
Vividus recommends creating a folder entitled Vividus in the same folder containing the THINKC application. Copy the vect folder, along with any other Vividus Source Code Libraries to this Vividus folder. This allows standard usage of angle brackets when indicating the inclusion of a header file from the THINKC "directory tree."
For projects which use the vect library, add the "vect.c" file found in the vect folder to the project. For FixedVector or IntVector routines, add the "ifvect.c" file to the project.
C files which make vect calls must include the "vect.h" file with the line:
#include <vect.h>.
The vect.h file contains vector typedefs and function prototypes for both the vect.c and ifvect.c files.
Include "vect.g" if the client C file needs reference to the global vectors vzero, vone, vxaxis, vyaxis, vzaxis, vnav, or the vWolrdCoordSys coordinate system.
Conventions:
Each vector data type is a structure of three components -- one component each for the x, y, and z components. The vector data types include:
vector A floating point vector representation. Each component is of type velem which is "typedef'd" as a "double."
IntVector An integer vector. Each component is declared as "int."
FixedVector A fixed point vector. Each component is declared as the Macintosh "Fixed" data type.
CoordSys A structure consisting of xAxis, yAxis, and zAxis vectors.
The Cartesian coordinate system used by all vect routines is the right-handed coordinate system as shown to the right. In the diagram the x axis points to the right out of the page and the y axis points to the right into the page. All three axis are orthogonal. Orthogonal is a mathematical term used when two lines intersect at right angles (90 degrees).
The right handed coordinate system.
All axis are at right angles.
The picture to the right illustrates the spherical coordinate system used by vect. Rho is the distance from the origin to the point P. Theta is the angle in the xy plane of the point P relative to the origin. Looking down the z axis, this angle is measured counter clockwise from the x axis. Phi is the angle between the z axis and the vector from the origin to the point P. Both theta and phi are always expressed in radians.
Spherical coordinate system.
This document will not explain vector math in any detail. The reader is urged to reference an elementary linear algebra book.
Programming Conventions:
The definitive reference for operations are the vect.h, vect.c, and ifvect.c files on disk.
Operations on single vectors:
All vect operations begin with a "v," an "iv", or an "fv." The "v," "iv," and "fv" indicate whether the operation pertains to a "vector," "IntVector," or "FixedVector" respectively.
Operations provided include: unit, copy, scale, sub, vect, add, sadd, cross, dot, mag, dist, valid, angle, mul, sphere2v, v2sphere, norm, matmul, cmin, and cmax. Not all operations are available for IntVectors and FixedVectors. Note that the first letter after the "v," "iv," or "fv" is never capitalized. Typically, the first parameters in the parameter list are input parameters and the last parameter in the parameter list is the resulting vector. When a vector parameter is passed it is always passed by its address.
To convert between vector types, the operations v2fv, fv2v, fv2iv, and iv2fv are provided.
Operations on lists of vectors:
Operations on lists of vectors include: Translate, Scale, Rotate, and Rotate3. These operations also follow the leading "v" convention. However, they have the first letter of their operation name capitalized. A vector list is identified by an integer count of the number of vectors and a pointer to an array of vectors.
Other Considerations:
Remember that "vectors" are rather large. When using a coprocessor they are 3 * 12 = 96 bytes in size.
Of paramount importance with such a library is client code readability and speed. Operator overloading would greatly help with the former --
v = a + b;
is much more readable than
vadd(&a, &b, &c);.
While this library could be more efficient, attempts were made to keep from doing anything ignorant. A subsequent step for increasing efficiency would be a C compiler which has operator overloading and "inlining." At the present time, THINKC has no operator overloading and an awkward inlining capability.
Even more related to speed is the computer hardware. Whenever a floating point coprocessor is available, Vividus recommends having the compiler generate "inline 68881" calls. Beyond this will be vector hardware -- something not expected anytime soon.
Questions:
Feel free to send your e-mail questions and comments. Please understand that Vividus consultants are busy and will feel an obligation to respond quicker to licensed users. Vividus may be reached at the following addresses:
CompuServe: 73067,542
Internet: 73067.542@compuserve.com
Change History:
This document describes the present 1.1 version of qd3d. New text in this document from its last revision appears in italics. For usage descriptions of new features or routines see the appropriate section of this qd3d documentation or the Cqd3dPort.h header file.
Addition and changes to the library for version 1.1:
Ñ Added vdist (distance) and vvalid (valid vector) functions.
Ñ Reformatted vect.h.
Ñ Added the globals vWorldCoordSys, and vnav (not a vector).
